<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <meta name="GENERATOR" content="Mozilla/4.77 [en] (X11; U; Linux 2.2.19-6.2.7 i686) [Netscape]">
   <title>Tomcat and SSL</title>
<!-- $Id  $ -->
<!--
   Copyright 1999-2004 The Apache Software Foundation
 
   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at
 
       http://www.apache.org/licenses/LICENSE-2.0
 
   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-->
<link rel="stylesheet" href="style.css">
<style type="text/css">
    .inlinetd {
        background-color: #E0E0E0;
        vertical-align: text-top;
        border-top: thick black;
        border-right: thick black;
        border-bottom: thick black;
        border-left: thick black;
    }
    .inlineth {
        background-color: #d0d0d0;
        border-top: thick black;
        border-right: thick black;
        border-bottom: thick black;
        border-left: thick black;
    }
    .inlinetable {
        width: 75%;
        border: thick;
        background-color: #000000;
    }
    .subsection { margin:20pt; }
    .note { margin:20pt; padding:5pt; background-color:#e0e0ff; }

    </style>
</head>
<body>
<!-- Banner element, all hail the Project! -->
<table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="100%" >
<tr>
    <td ALIGN=LEFT WIDTH="50%"><a href="http://jakarta.apache.org/index.html"><img SRC="images/banner.gif" ALT="The Jakarta Project" BORDER=0 height=48 width=505></a></td>

    <td ALIGN=RIGHT WIDTH="50%"><img SRC="images/tomcat.gif" ALT="The mighty Tomcat - Meow!" BORDER=0 height=71 width=100></td>
</tr>
</table>

<h1>
Tomcat SSL Configuration</h1>

<table border="0" cellpadding="0" cellspacing="0">
<tr><td colspan="2"><b>Authors:</b><br><br></td></tr>
<tr>
   <td>Henri Gomez</td>
   <td><tt>&lt;<a href="mailto:hgomez@slib.fr">hgomez@slib.fr</a>&gt;</tt></td>
</tr>
<tr>
   <td>Christopher Cain&nbsp;&nbsp;</td>
   <td><tt>&lt;<a href="mailto:ccain@apache.org">ccain@apache.org</a>&gt;</tt></td>
</tr>
<tr>
   <td>Eric Rescorla</td>
   <td><tt>&lt;<a href="mailto:ekr@rtfm.com">ekr@rtfm.com</a>&gt;</tt></td>
</tr>
</table>
<br>

<hr>

<h2>
Table of Contents</h2>

<ul>
<li>
<a href="#s1">Introduction to SSL</a></li>

<li>
<a href="#s2">Tomcat and SSL</a></li>

<li>
<a href="#s8">Certificates</a></li>

<li>
<a href="#s3">Building Tomcat with SSL support</a></li>

<li>
<a href="#s4">Tomcat with Apache and mod_jk</a></li>

<li>
<a href="#s5">SSL via Apache</a></li>

<li>
<a href="#s6">SSL Standalone</a></li>

<li>
<a href="#s9">General Tips on Running SSL</a></li>

<li>
<a href="#s10">Troubleshooting SSL Standalone</a></li>

<li>
<a href="#s7">Credits</a></li>
</ul>

<hr>
<h2>
<a NAME="s1"></a>Introduction to SSL</h2>
SSL, or Secure Sockets Layer, is a technology which allows web browsers and
web servers to communicate over a secured connection. This means that the data
being sent is encrypted by one side, transmitted, then decrypted by the other
side prior to any processing. This is a two-way process, meaning that both the
server <i>and</i> the browser encrypt all traffic before sending out data.
<p>
Another important aspect of the SSL protocol is <em>Authentication</em>. This
means that during your initial attempt to communicate with a web server over a
secure connection, that server will present your web browser with a set of
credentials, in the form of a <em><a href="#s8">Certificate</a></em>, as proof
that the site is who and what it claims to be. In certain cases, the server may
also request a certificate from your web browser, asking for proof that
<em>you</em> are who you claim to be. This is known as <em>Client
Authentication,</em> although in practice it is used primarily for
business-to-business (B2B) transactions rather than with typical site users.
Most SSL-enabled web servers do not request Client Authentication.
<br>
<hr>

<h2>
<a NAME="s2"></a>Tomcat and SSL</h2>
It is important to note that configuring Tomcat to take advantage of
secure sockets is usually only necessary when running it as a standalone
web server. When running Tomcat primarily as a Servlet/JSP container behind
another web server, such as Apache or Microsoft IIS, it is usually necessary
to configure the primary web server to handle the SSL connections from users.
Typically, this server will negotiate all SSL-related functionality, then
pass on any requests destined for the Tomcat container only after decrypting
those requests. Likewise, Tomcat will return cleartext responses, which will
then be encrypted by the primary server before being returned to the user's
browser. In this environment, Tomcat knows that communications between the
primary web server and the client are taking place over a secure connection
(because your application needs to be able to ask about this), but it does
not participate in the encryption or decryption itself.
<p>
Information on configuring Apache for SSL can be found at either the
<a href="http://www.apache-ssl.org">Apache-SSL</a> pages, or the
<a href="http://www.modssl.org">apache-mod_ssl</a> project. For information on
configuring Tomcat to communicate with an SSL-enabled Apache server, see the
<em><a href="#s4">Tomcat with Apache and mod_jk</a></em> section.
<BR><BR>
<B>Note:</B> SSL with Tomcat standalone requires JDK 1.2 or greater.
<BR>
<hr>

<h2>
<a NAME="s8"></a>Certificates</h2>
In order to implement SSL, a web server must have an associated certificate
for each external interface (IP address) that accepts secure connections.
The theory behind certificates is that a server should provide some kind of
reasonable assurance that its owner is who you think it is, particularly
before receiving any sensitive information. While a broader explanation of
certificates is beyond the scope of this document, think of a certificate
as a digital "driver's license" for an Internet address. It states what
company a site is associated with, along with some basic contact
information about the site's owner and/or administrator.
<p>
This "driver's license" is cryptographically signed by its issuer, and is
therefore extremely difficult for anyone else to forge. For sites involved
in e-commerce, or any other business transaction in which authentication of
identity is important, a certificate is typically purchased from a well-known
<em>Certificate Authority</em> (CA) such as VeriSign or Thawte. Such
certificates can be electronically verified --- in effect, the CA will vouch
for the authenticity of the certificates that it grants, so you can,
ostensibly, trust that a given certificate is valid if you trust the CA who
granted it.
<p>
In many cases, however, authentication is not really a concern. An
administrator may simply want to ensure that the data being transmitted and
received by the server is private and cannot be snooped by anyone who may be
eavesdropping on the connection. In such cases one is often tempted to
use a "self-signed certificate"--one which has been signed only by the
owner. Such a certificate obviously doesn't provide any guarantee of
who the certificate owner is; there's nothing stopping me from making myself a certificate claiming to be George W. Bush.
<p>
What's less obvious is that using such certificates weakens the
secrecy of your data as well. The attack works like this: when the
client attempts to connect to the server the attacker hijacks the
connection. He sends the client his own self-signed certificate which
has the same <B>name</B> as that in the server's self-signed certificate.
The attacker then connects to the real server himself. When the client
sends data to the server the attacker reads it and then sends it along
to the real server. This is called a <B>man-in-the-middle</B> attack.
<p>
The take-home message is that if you're worried about attackers who
can write data to the network (this is called an active attack) then
self-signed certificates won't protect you. If you're worried about
attackers who can only read data off the network (this is called
a passive attack) then self-signed certificates work fine. In general,
you <EM>should</EM> worry about active attack and so self-signed
certificates aren't that good.
<p>
Nevertheless, self-signed certificates are fantastically useful for testing
and they are easily created with Java's <code>keytool</code> program or
using OpenSSL.
<br>
<hr>
<h2>
<a NAME="s3"></a>Building Tomcat with SSL support</h2>
If you want to build Tomcat with support for SSL, be careful of your
classpath. I usually clear the <code>CLASSPATH</code> environment variable in
order to avoid possible conflicts in jars. A common case of conflict is for XML
parsers (xerces &amp; jaxp). Tomcat required a recent XML parser, such as
Apache Group's <A HREF="http://xml.apache.org/xerces-j/index.html">Xerces</A>
or Sun's <A HREF="http://java.sun.com/xml/jaxp.html">JAXP</A>.
<p>
You now have two options for building Tomcat with SSL support: Sun's JSSE
and Claymore Systems's PureTLS. The functionality that they offer is
roughly equivalent. The primary relevant difference is in licensing:
PureTLS is open source (BSD-style license) and JSSE is closed source.
Therefore, if you want to redistribute compiled versions of Tomcat or
just look at the source of your SSL/TLS implementation you must
use PureTLS.
<p>
At build time (via Ant), Tomcat will automatically build as much SSL support
as it can. If you have both PureTLS and JSSE in your <CODE>CLASSPATH</CODE>,
Tomcat will automatically build with support for both. At run time, Tomcat
will automatically select whatever library is present (if both are present,
PureTLS will be selected). You can control which implementation is used
via configuration file.
<br>
<hr>
<h2>
<a NAME="s4"></a>Tomcat with Apache and mod_jk</h2>
If you use Apache with SSL (apache-ssl or apache-mod_ssl), the Apache connector
mod_jk will be able to forward Tomcat SSL information if the JkExtractSSL
directive is present in your httpd.conf.
<p>Forwarded SSL Information is:
<br>&nbsp;
<table BORDER WIDTH="75%" >
<tr>
<td>HTTPS</td>

<td>Apache Redirect to Tomcat from an SSL Area</td>
</tr>

<tr>
<td>SSL_SESSION_ID</td>

<td>SSL session ID</td>
</tr>

<tr>
<td>SSL_CIPHER</td>

<td>SSL CIPHER used</td>
</tr>

<tr>
<td>SSL_CLIENT_CERT</td>

<td>SSL Certificate of client</td>
</tr>
</table>

<p>Since apache-ssl and apache-mod_ssl use different environment variables, you
can adapt SSL variables via the following JK vars:
<ul>
<li>
JkExtractSSL</li>

<li>
JkHTTPSIndicator</li>

<li>
JkSESSIONIndicator</li>

<li>
JkCIPHERIndicator</li>

<li>
JkCERTSIndicator:</li>
</ul>
Here is an example of some directives to include in httpd.conf for use with
mod_ssl:
<p><font face="Courier New, Courier, mono"><font size=-1># Should mod_jk
send SSL information to Tomcat (default is On)</font></font>
<br><font face="Courier New, Courier, mono"><font size=-1>JkExtractSSL
On</font></font>
<br><font face="Courier New, Courier, mono"><font size=-1># What is the
indicator for SSL (default is HTTPS)</font></font>
<br><font face="Courier New, Courier, mono"><font size=-1>JkHTTPSIndicator
HTTPS</font></font>
<br><font face="Courier New, Courier, mono"><font size=-1># What is the
indicator for SSL session (default is SSL_SESSION_ID)</font></font>
<br><font face="Courier New, Courier, mono"><font size=-1>JkSESSIONIndicator
SSL_SESSION_ID</font></font>
<br><font face="Courier New, Courier, mono"><font size=-1># What is the
indicator for client SSL cipher suit (default is SSL_CIPHER)</font></font>
<br><font face="Courier New, Courier, mono"><font size=-1>JkCIPHERIndicator
SSL_CIPHER</font></font>
<br><font face="Courier New, Courier, mono"><font size=-1># What is the
indicator for the client SSL certificated (default is SSL_CLIENT_CERT)</font></font>
<br><font face="Courier New, Courier, mono"><font size=-1>JkCERTSIndicator
SSL_CLIENT_CERT</font></font>
<p>When using mod_jk with Apache &amp; mod_ssl, it is essential to specify
"SSLOptions +StdEnvVars +ExportCertData" in the httpd.conf file.
<br>Otherwise, mod_ssl will not produce the neccessary environment variables
for mod_jk. (Tilo Christ &lt;tilo.christ@med.siemens.de&gt;).
<p>Warning, even though mod_jk supports both ajp12 (an old version from
ApacheJServ) and ajp13, only ajp13 can forward SSL information to Tomcat.
<br>
<hr>
<h2>
<a NAME="s5"></a>SSL via Apache</h2>
mod_jk supports the VirtualHost directive of Apache. This is especially
useful when using Apache mod_ssl with Tomcat.
<br>The following configuration will easily secure your webapps via Apache SSL
support (be careful when setting these jk variables outside VirtualHost
directives):
<p><font face="Courier New, Courier, mono"><font size=-1>JkWorkersFile
/etc/httpd/conf/workers.properties</font></font>
<br><font face="Courier New, Courier, mono"><font size=-1>JkLogFile /var/log/httpd/mod_jk.log</font></font>
<br><font face="Courier New, Courier, mono"><font size=-1>JkLogLevel warn</font></font>
<p>The jk redirect stuff can be set in virtual hosts:&nbsp;<virtualhost _default_:443>
<p><font face="Courier New, Courier, mono"><font size=-1>&lt;VirtualHost
_default_:443&gt;</font></font>
<br><font face="Courier New, Courier, mono"><font size=-1>SSLEngine on</font></font>
<br><font face="Courier New, Courier, mono"><font size=-1>SSLCipherSuite
ALL:!ADH:!EXP56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL</font></font>
<p><font face="Courier New, Courier, mono"><font size=-1># other SSL stuff</font></font>
<p><font face="Courier New, Courier, mono"><font size=-1>Alias /alesia
"/var/tomcat/webapps/alesia"&nbsp;</font></font><directory "/var/tomcat/webapps/alesia">
<br><font face="Courier New, Courier, mono"><font size=-1>&lt;Directory
"/var/tomcat/webapps/alesia"></font></font></directory>
<br><directory "/var/tomcat/webapps/alesia"><font face="Courier New, Courier, mono"><font size=-1>Options
Indexes FollowSymLinks&nbsp;</font></font></directory>
<br><font face="Courier New, Courier, mono"><font size=-1>&lt;/Directory></font></font>
<p><font face="Courier New, Courier, mono"><font size=-1>JkMount /alesia/servlet/*
ajp13</font></font>
<br><font face="Courier New, Courier, mono"><font size=-1>JkMount /alesia/*.jsp
ajp13&nbsp;</font></font><location "/alesia/WEB-INF/">
<br></location>
<br><font face="Courier New, Courier, mono"><font size=-1>&lt;Location
"/alesia/WEB-INF/"&gt;</font></font>
<br><font face="Courier New, Courier, mono"><font size=-1>AllowOverride
None</font></font>
<br><font face="Courier New, Courier, mono"><font size=-1>Deny from all</font></font>
<br><font face="Courier New, Courier, mono"><font size=-1>&lt;/Location&gt;</font></font>
<p><font face="Courier New, Courier, mono"><font size=-1>&lt;/VirtualHost&gt;</font></font><virtualhost _default_:443></virtualhost>
<br>
<hr>

<h2>
<a NAME="s6"></a>SSL Standalone</h2>

In order to configure Tomcat standalone for SSL support, you need to create
(or import) an SSL certificate. For more information about SSL and
certificates, you might find the following resources helpful:
<ul>
   <li><a href="http://www.openssl.org">OpenSSL</a> (Open Source SSL
       implementation)
   <li><a href="http://www.modssl.org">ModSSL</a> (SSL support for Apache)
   <li><a href="http://www.cryptix.org">Cryptix</a> (Open Source Java crypto
library)
</ul>
<P>
If you have either PureTLS or JSSE installed, you might as well use that
for your SSL support. If you have neither installed, you will need to
download and install one of them.
<p>
<hr>
<h2>SSL Support with JSSE</h3>
<p>
<h3>Download and Install JSSE</h3>

<h3>1. Download and Install JSSE</h3>

Download the <em>Java Secure Socket Extensions</em> (JSSE) package,
version 1.0.2 or later, from
<a href="http://java.sun.com/products/jsse/">http://java.sun.com/products/jsse/
</a>. If you are running JDK 1.4 (currently in beta), these classes have
been integrated directly into the JDK, so you can skip this entire step.
<br><br>
After expanding the package, there are two ways to make it available to
Tomcat (choose one or the other):<br>
<ul>
<li>You can make JSSE an <em>installed extension</em> by copying all three JAR
    files (<code>jcert.jar</code>, <code>jnet.jar</code>, and
    <code>jsse.jar</code>) into your <code>$JAVA_HOME/jre/lib/ext</code>
    directory.</li>
<li>Alternatively, you can make these jars available via the classpath that is
    passed to Tomcat on startup. This will need to be done in the appropriate
    startup script for your environment (
    <code>$TOMCAT_HOME/bin/tomcat</code> in Unix, or
    <code>%TOMCAT_HOME%\bin\tomcat.bat</code> in Windows).</li>
</ul>
<b>Note:</b> The system classpath is effectively ignored by Tomcat, so
including the JSSE jars there will <i>not</i> make them available for
use by the Tomcat engine  during runtime (although it will not conflict with
the two methods described above if they <i>do</i> happen to be in the system
classpath). Also, do <em>not</em> copy these jars into any of the internal
Tomcat repositories (the <code>$TOMCAT_HOME/lib/*</code> directories,
individual webapp directories, etc.). Doing so may cause Tomcat to fail, as
these libraries should only be loaded by the system classloader.

<h3>2. Prepare the Certificate Keystore</h3>
<b>Note:</b> In order to execute the <code>keytool</code> command-line utility,
the JSSE jars <em>must</em> be either in the classpath or an installed
extension.
<br><br>
A "keystore" is essentially just a repository file for cryptographic objects,
such as keys and certificates. Tomcat currently operates only on
<code>JKS</code> format keystores.  This is Java's standard "Java KeyStore"
format, and is the format created by the <code>keytool</code> command-line
utility.  This tool is included in the JDK.
<br><br>
<b>To create a new keystore from scratch, containing a single self-signed
certificate, execute the following from a terminal command line:</b>
<br><br>

<blockquote>
<code>
%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA
</code>
(Windows)<br>
<code>
$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA
</code>
(Unix)
</blockquote>
<br>
(The RSA algorithm should be preferred as a secure algorithm, and also
to ensure general compatibility with other servers and components such as
Netscape and IIS.)
<br><br>
This command will create a new file, in the home directory of the user
under which you run it, named "<code>.keystore</code>".  To specify a
different location or filename, add the <code>-keystore</code> parameter,
followed by the complete pathname to your keystore file,
to the <code>keytool</code> command shown above. For example:
<br><br>

<blockquote>
<code>
%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA \
  -keystore /path/to/my/keystore
</code>
(Windows)<br>
<code>
$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA \
  -keystore /path/to/my/keystore
</code>
(Unix)
</blockquote>
<br>

After executing the <code>keytool</code> command, you will first be prompted
for the keystore password.  The default password used by Tomcat is
"<code>changeit</code>" (all lower case), although you can specify a custom
password if you like. Again, this will need to be reflected in the
<code>server.xml</code> configuration file.
<br><br>

<tt><font size=-1>[root@www.vercingetorix.org /root]# $JAVA_HOME/bin/keytool -genkey -alias
tomcat -keyalg RSA</font></tt>
<br><tt><font size=-1>Enter keystore password:&nbsp; changeit</font></tt>
<br><tt><font size=-1>What is your first and last name?</font></tt>
<br><tt><font size=-1>&nbsp; [Unknown]:&nbsp; www.vercingetorix.org</font></tt>
<br><tt><font size=-1>What is the name of your organizational unit?</font></tt>
<br><tt><font size=-1>&nbsp; [Unknown]:&nbsp; Chief</font></tt>
<br><tt><font size=-1>What is the name of your organization?</font></tt>
<br><tt><font size=-1>&nbsp; [Unknown]:&nbsp; Gaulois</font></tt>
<br><tt><font size=-1>What is the name of your City or Locality?</font></tt>
<br><tt><font size=-1>&nbsp; [Unknown]:&nbsp; Alesia</font></tt>
<br><tt><font size=-1>What is the name of your State or Province?</font></tt>
<br><tt><font size=-1>&nbsp; [Unknown]:&nbsp; 50</font></tt>
<br><tt><font size=-1>What is the two-letter country code for this unit?</font></tt>
<br><tt><font size=-1>&nbsp; [Unknown]:&nbsp; FR</font></tt>
<br><tt><font size=-1>Is &lt;CN=www.vercingetorix.org, OU=Chief, O=Gaulois,
L=Alesia, ST=50, C=FR&gt; correct?</font></tt>
<br><tt><font size=-1>&nbsp; [no]:&nbsp; yes</font></tt>
<br><br>

Finally, you will be prompted for the <em>key password</em>, which is the
password specifically for this Certificate (as opposed to any other
Certificates stored in the same keystore file).  You <strong>MUST</strong>
use the same password here as was used for the keystore password itself.
(Currently, pressing the ENTER at this prompt will automatically do this.)
<br><br>
<b>To import an existing certificate into a JKS keystore:</b>
<br><br>

It is possible to import certificates generated with <a href="http://www.openssl.org">OpenSSL</a>.
Here are the steps needed to generate such certs with OpenSSL :
<ul>
<li>
To generate a new request and a new key</li>

<pre><font face="Courier New, Courier, mono">openssl req -new -out REQ.pem -keyout KEY.pem</font></pre>

<li>
To generate a self signed x509 certificate from a certificate request using
a supplied key, and we want to see the text form of the output certificate
(which we will put in the file selfSign.pem)</li>

<pre><font face="Courier New, Courier, mono"><font size=-1>openssl req -x509
-in REQ.pem -key KEY.pem -out CERT.pem</font></font></pre>

<li>
Verify that the signature is correct on a certificate request.</li>

<pre><font face="Courier New, Courier, mono"><font size=-1>openssl req -verify
-in REQ.pem</font></font></pre>

<li>
Verify that the signature was made using a specified public key</li>

<pre><font face="Courier New, Courier, mono"><font size=-1>openssl req -verify
-in REQ.pem -key KEY.pem</font></font></pre>

<li>
Print the contents of a certificate request</li>

<pre><font face="Courier New, Courier, mono"><font size=-1>openssl req -text
-in REQ.pem</font></font></pre>

<li>
To import the CERT in keystore, you just do next :</li>

<pre><font face="Courier New, Courier, mono"><font size=-1>keytool -import
-v -trustcacerts -alias tomcat -file</font></font></pre>

<pre><font face="Courier New, Courier, mono"><font size=-1>CERT.pem</font></font></pre>
</ul>

For more information, please read the documentation (in your JDK
documentation package) about <code>keytool</code>.
<br>
<hr>
<h2>SSL Support with PureTLS</h2>
<h3>1. Downloading and Installing PureTLS</h3>
The easiest way to download PureTLS is by simply downloading the
prebuilt version from <a href="http://www.rtfm.com/puretls/prebuilt.html">
http://www.rtfm.com/puretls/prebuilt.html</a>. This version contains
all the jar files you will need in order to use PureTLS in one package.
After expanding the package, there are two ways to make it available to
Tomcat (choose one or the other):<br>
<ul>
 <li>You can make PureTLS an <em>installed extension</em> by copying all three JAR
    files (<code>cryptix32.jar</code>, <code>puretls.jar</code>, and
    <code>cryptix-asn1.jar</code>) into your <code>$JAVA_HOME/jre/lib/ext</code>
    directory.</li>
 <li>Alternatively, you can make these jars available via the classpath that is
    passed to Tomcat on startup. This will need to be done in the appropriate
    startup script for your environment (
    <code>$TOMCAT_HOME/bin/tomcat</code> in Unix, or
    <code>%TOMCAT_HOME%\bin\tomcat.bat</code> in Windows).</li>
</ul>
<b>Note:</b> The system classpath is effectively ignored by Tomcat, so
including the PureTLS jars there will <i>not</i> make them available for
use by the Tomcat engine  during runtime (although it will not conflict with
the two methods described above if they <i>do</i> happen to be in the system
classpath). Also, do <em>not</em> copy these jars into any of the internal
Tomcat repositories (the <code>$TOMCAT_HOME/lib/*</code> directories,
individual webapp directories, etc.). Doing so may cause Tomcat to fail, as
these libraries should only be loaded by the system classloader.
<p>
Alternately, you can download the PureTLS source distribution from
<a href="http://www.rtfm.com/puretls">http://www.rtfm.com/puretls
</a> and build it yourself. You will also need to install
Cryptix 3.2 from <a href="http://www.cryptix.org/">http://www.cryptix.org/</a>.
Once you've built Cryptix and PureTLS, install them as described above.
<p>
<h3>2. Obtaining Keys and Certificates</h3>
<p>
PureTLS uses OpenSSL-style keyfiles. If you have an OpenSSL key
you can simply copy it somewhere and point Tomcat at it.
Sometimes when people use OpenSSL they store their keys and
certificates in separate files, such as <code>key.pem</code>
and <code>cert.pem</code>. PureTLS expects a single file which
you can create by just concatenating the two files. For instance:
<code>cat key.pem cert.pem &gt; keyfile.pem</code>.
<p>
PureTLS does not currently allow you to make self-signed certificates.
However, a number of sample certificate files are included in the
PureTLS distribution. For testing purposes you can use the file
<code>rsa-server.pem</code> which has the password <code>password</code>.
<p>
Finally, PureTLS allows you to create a certificate request using
the <code>COM.claymoresystems.ptls.cert.CertRequest</code> class.
With PureTLS in your classpath, execute <code>COM.claymoresystems.cert.CertRequest &lt;keyfile-name&gt; RSA</code>. Then type your keyfile password on the
console (currently this is echoed which is rather a bug). PureTLS will think for a while and then generate a key in <code>keyfile-name</code>. The certificate request (in Netscape format) will be printed on the screen and can be
cut and pasted into your CA's web page. When you get your certificate
attach it to the end of your keyfile.
<h3>3. Trust Management for Client Authentication</h3>
If you intend to require your clients to authenticate with certificates
you will need to decide what CAs you trust. PureTLS gets this information
from a <i>root file</i> which is just the concatenation of the trusted
root CA certificates. You specify that file to Tomcat using the
<code>rootlist</code> attribute in the configuration file.
<hr>

<h3>3. Edit the Tomcat configuration file</h3>

To configure a secure (SSL) HTTP connector for Tomcat, verify that it is activated in
the <CODE>$TOMCAT_HOME/conf/server.xml</CODE> file (the standard version of this file,
as shipped with Tomcat, contains a simple example which is commented-out by default).
<BLOCKQUOTE>
<p>Syntax for Tomcat 3.2 :
<p><tt><font size=-1>&lt;Connector className="org.apache.tomcat.service.PoolTcpConnector"&gt;</font></tt>
<br><tt><font size=-1>&lt;Parameter name="handler" value="org.apache.tomcat.service.http.HttpConnectionHandler"/&gt;</font></tt>
<br><tt><font size=-1>&lt;Parameter name="port" value="8443"/&gt;</font></tt>
<br><tt><font size=-1>&lt;Parameter name="socketFactory" value="org.apache.tomcat.net.SSLSocketFactory"
/&gt;</font></tt>
<br><tt><font size=-1>&lt;Parameter name="keystore" value="/var/tomcat/conf/keystore"
/&gt;</font></tt>
<br><tt><font size=-1>&lt;Parameter name="keypass" value="mynewpass"/&gt;</font></tt>
<br><tt><font size=-1>&lt;Parameter name="clientAuth" value="false"/&gt;</font></tt>
<br><tt><font size=-1>&lt;/Connector&gt;</font></tt><tt></tt>
<p>Syntax for Tomcat 3.3 :
<p><tt><font size=-1>&lt;Http10Connector</font></tt>
<br><tt><font size=-1>&nbsp; port="8443"</font></tt>
<br><tt><font size=-1>&nbsp; secure="true"</font></tt>
<br><tt><font size=-1>&nbsp; keystore="/var/tomcat/conf/keystore"</font></tt>
<br><tt><font size=-1>&nbsp; keypass="mynewpass"</font></tt>
<br><tt><font size=-1>&nbsp; clientauth="false" /&gt;</font></tt><font size=-1></font>
</BLOCKQUOTE>
In the above examples, we indicate that the keystore is file located at
<code>/var/tomcat/conf/keystore</code>, and the password if "mynewpass". Again,
these attributes can be skipped if the Tomcat defaults were used. Also, we
specified that we don't want to enforce client authentication. Also, note the
case difference between Tomcat 3.2 and Tomcat 3.3 (i.e. &quot;clientAuth&quot;
versus &quot;clientauth&quot;).
<P>
For JSSE, the <i>presence</i> of the clientauth parameter will enforce
client authentication, regardless of the parameter value.  For PureTLS,
this decision is based on the <i>value</i> of the clientauth parameter.
<P>
By default, Tomcat chooses whatever SSL implementation is available,
with preference given to PureTLS over JSSE if both are available. You
can specify the exact implementation you want using the <code>SSLImplementation</code>
parameter, like so:
<p><tt><font size=-1>&lt;Http10Connector</font></tt>
<br><tt><font size=-1>&nbsp; port="8443"</font></tt>
<br><tt><font size=-1>&nbsp; secure="true"</font></tt>
<br><tt><font size=-1>&nbsp; keystore="/var/tomcat/conf/keystore"</font></tt>
<br><tt><font size=-1>&nbsp; keypass="mynewpass"</font></tt>
<br><tt><font size=-1>&nbsp; clientauth="false" </font></tt>
<br><tt><font size=-1>&nbsp; SSLImplementation="org.apache.tomcat.util.net.PureTLSImplementation" </font></tt> /&gt;</font></tt>
<P>
<code>SSLImplementation</code> can be the name of any class that implements
<code>org.apache.tomcat.util.net.SSLImplementation</code>. The values built
into Tomcat are <code>org.apache.tomcat.util.net.PureTLSImplementation</code> for PureTLS
and <code>org.apache.tomcat.util.net.JSSEImplementation</code> for JSSE.

<hr>

<h2>
<a NAME="s9"></a>General Tips on Running SSL</h2>
The first time a user attempts to access a secured page on your site,
he or she is typically presented with a dialog containing the details of
the certificate (such as the company and contact name), and asked if he or she
wishes to accept the certificate as valid and continue with the transaction.
Some browsers will provide an option for permanently accepting a given
certificate as valid, in which case the user will not be bothered with a
prompt each time they visit your site. Other browsers do not provide this
option. Once approved by the user, a certificate will be considered valid
for at least the entire browser session.
<p>
Also, while the SSL protocol was designed to be as efficient as securely
possible, encryption/decryption is a computationally expensive process from
a performance standpoint. It is not strictly necessary to run an entire
web application over SSL, and indeed a developer can pick and choose which
pages require a secure connection and which do not. For a reasonably busy
site, it is customary to only run certain pages under SSL, namely those
pages where sensitive information could possibly be exchanged. This would
include things like login pages, personal information pages, and shopping
cart checkouts, where credit card information could possibly be transmitted.
Any page within an application can be requested over a secure socket by
simply prefixing the address with <code>https:</code> instead of
<code>http:</code>. Any pages which absolutely require a secure connection
should check the protocol type associated with the page request and take the
appropriate action if the <code>https</code> protocol is not specified.

<hr>

<h2>
<a NAME="s10"></a>Troubleshooting SSL Standalone</h2>
Here is a list of common problems that you may encounter when setting up
Tomcat standalone for SSL, and what to do about them.</p>

<ul>

<li><I>I am seeing "java.security.NoSuchAlgorithmException" errors.</I>
    <blockquote>
    <p>The JVM cannot find the JSSE JAR files, or there was a problem in
    loading the JSSE Provider. Please ensure that the JSSE jars have been
    appropriately installed.</p>
    </blockquote>
</li>

<li><I>When Tomcat starts up, I get an exception like
    "java.io.FileNotFoundException: {some-directory}/{some-file} not found".</I>
    <blockquote>
    <p>A likely explanation is that Tomcat cannot find the keystore file
    where it is looking. By default, Tomcat expects the keystore file to
    be named <code>.keystore</code> in the user home directory under which
    Tomcat is running (which may or may not be the same as yours :-). If
    the keystore file is anywhere else, you will need to add the
    <code>keystore</code> parameter/attribute to the secure connector in the
    Tomcat configuration file (as outlined in the
    <A HREF="#s6">Standalone SSL section</A>).</p>
    </blockquote>
</li>

<li><I>When Tomcat starts up, I get an exception like
    "java.io.FileNotFoundException: Keystore was tampered with, or
    password was incorrect".</I>
    <blockquote>
    <p>Assuming that someone has not <em>actually</em> tampered with
    your keystore file, the most likely cause is that Tomcat is using
    a different password than the one you specified when creating the
    keystore file. To fix this, you can either recreate the keystore
    file, or you can add/update the <code>keypass</code> parameter/attribute
    on the secure connector in the Tomcat configuration file (as outlined in
    the <A HREF="#s6">Standalone SSL section</A>).

    <P><strong>REMINDER</strong> - Passwords are case sensitive!</p>
    </blockquote>
</li>

</ul>

<p>If you are still having problems, a good source of information is the
<strong>TOMCAT-USER</strong> mailing list. You can find pointers to archives
of previous messages on this list, as well as subscription and unsubscription
information, at
<a href="http://jakarta.apache.org/site/mail.html">http://jakarta.apache.org/site/mail.html</a>.</p>
<br>
<hr>

<h2>
<a NAME="s7"></a>Credits</h2>
This document was written by <a href="mailto:hgomez@slib.fr">Henri Gomez</a>, <A HREF="mailto:ccain@apache.org">Christopher Cain</A> and <A href="mailto:ekr@rtfm.com">Eric Rescorla</a>. Thanks to both Tilo
Christ &lt;tilo.christ@med.siemens.de&gt; and hgopal@cmcltd.com for additional
contributions.</P>
<br>&nbsp;
<table BORDER=0 CELLSPACING=0 CELLPADDING=10 WIDTH="100%" >
<tr>
<td>
<div class="fineprint">Copyright &copy;1999-2001 The Apache Software Foundation</div>

<p><br><a href="http://jakarta.apache.org/legal.html">Legal Stuff They
Make Us Say</a>
<br><a href="http://jakarta.apache.org/contact.html">Contact Information</a></td>
</tr>
</table>

</body>
</html>
